---
title: Basic Example
---

import { FileTree } from '@astrojs/starlight/components';

This example code is bare-bones to show you what this framework can do.
Under the hood of this interactive demo, we run Style Dictionary through the Node API in a way that is equivalent to running the CLI command:

```bash
npx style-dictionary build
```

~ sd-playground

```json tokens
{
  "colors": {
    "base": {
      "gray": {
        "light": { "value": "#CCCCCC", "type": "color" },
        "medium": { "value": "#999999", "type": "color" },
        "dark": { "value": "#111111", "type": "color" }
      },
      "red": { "value": "#FF0000", "type": "color" },
      "green": { "value": "#00FF00", "type": "color" }
    },
    "font": {
      "base": { "value": "{colors.base.red}", "type": "color" },
      "secondary": { "value": "{colors.base.green}", "type": "color" },
      "tertiary": { "value": "{colors.base.gray.light}", "type": "color" }
    }
  },
  "size": {
    "font": {
      "small": {
        "value": "0.75",
        "type": "fontSize",
        "comment": "the small size of the font"
      },
      "medium": {
        "value": "1",
        "type": "fontSize",
        "comment": "the medium size of the font"
      },
      "large": {
        "value": "2",
        "type": "fontSize",
        "comment": "the large size of the font"
      },
      "base": {
        "value": "{size.font.medium}",
        "type": "fontSize",
        "comment": "the base size of the font"
      }
    }
  }
}
```

```json config
{
  "source": ["tokens.json"],
  "platforms": {
    "scss": {
      "transformGroup": "scss",
      "buildPath": "build/scss/",
      "files": [
        {
          "destination": "_variables.scss",
          "format": "scss/variables"
        }
      ]
    },
    "android": {
      "transformGroup": "android",
      "buildPath": "build/android/",
      "files": [
        {
          "destination": "font_dimens.xml",
          "format": "android/fontDimens"
        },
        {
          "destination": "colors.xml",
          "format": "android/colors"
        }
      ]
    },
    "compose": {
      "transformGroup": "compose",
      "buildPath": "build/compose/",
      "files": [
        {
          "destination": "StyleDictionaryColor.kt",
          "format": "compose/object",
          "options": {
            "className": "StyleDictionaryColor",
            "packageName": "StyleDictionaryColor"
          },
          "filter": {
            "type": "color"
          }
        },
        {
          "destination": "StyleDictionarySize.kt",
          "format": "compose/object",
          "options": {
            "className": "StyleDictionarySize",
            "packageName": "StyleDictionarySize",
            "type": "float"
          },
          "filter": {
            "type": "fontSize"
          }
        }
      ]
    },
    "ios": {
      "transformGroup": "ios",
      "buildPath": "build/ios/",
      "files": [
        {
          "destination": "StyleDictionaryColor.h",
          "format": "ios/colors.h",
          "options": {
            "className": "StyleDictionaryColor",
            "type": "StyleDictionaryColorName"
          },
          "filter": {
            "type": "color"
          }
        },
        {
          "destination": "StyleDictionaryColor.m",
          "format": "ios/colors.m",
          "options": {
            "className": "StyleDictionaryColor",
            "type": "StyleDictionaryColorName"
          },
          "filter": {
            "type": "color"
          }
        },
        {
          "destination": "StyleDictionarySize.h",
          "format": "ios/static.h",
          "options": {
            "className": "StyleDictionarySize",
            "type": "float"
          },
          "filter": {
            "type": "fontSize"
          }
        },
        {
          "destination": "StyleDictionarySize.m",
          "format": "ios/static.m",
          "options": {
            "className": "StyleDictionarySize",
            "type": "float"
          },
          "filter": {
            "type": "fontSize"
          }
        }
      ]
    },
    "ios-swift": {
      "transformGroup": "ios-swift",
      "buildPath": "build/ios-swift/",
      "files": [
        {
          "destination": "StyleDictionary+Class.swift",
          "format": "ios-swift/class.swift",
          "options": {
            "className": "StyleDictionaryClass"
          }
        },
        {
          "destination": "StyleDictionary+Enum.swift",
          "format": "ios-swift/enum.swift",
          "options": {
            "className": "StyleDictionaryEnum"
          }
        },
        {
          "destination": "StyleDictionary+Struct.swift",
          "format": "ios-swift/any.swift",
          "options": {
            "className": "StyleDictionaryStruct",
            "imports": "SwiftUI",
            "objectType": "struct",
            "accessControl": "internal"
          }
        }
      ]
    },
    "ios-swift-separate-enums": {
      "transformGroup": "ios-swift-separate",
      "buildPath": "build/ios-swift/",
      "files": [
        {
          "destination": "StyleDictionaryColor.swift",
          "format": "ios-swift/enum.swift",
          "options": {
            "className": "StyleDictionaryColor"
          },
          "filter": {
            "type": "color"
          }
        },
        {
          "destination": "StyleDictionarySize.swift",
          "format": "ios-swift/enum.swift",
          "options": {
            "className": "StyleDictionarySize"
          },
          "filter": {
            "type": "fontSize"
          }
        }
      ]
    }
  }
}
```

:::note
You can click the download button to the top right of the interactive demo to download a ZIP file for this particular example.
This contains a README.md telling you which commands to run to get this example running locally.
You will need NodeJS and NPM installed, Node v18 minimum being required.
:::

You should see something like this output in the console:

```
scss
✔︎  build/scss/_variables.scss

android
✔︎  build/android/font_dimens.xml
✔︎  build/android/colors.xml

compose
✔︎ build/compose/StyleDictionaryColor.kt
✔︎ build/compose/StyleDictionarySize.kt

ios
✔︎  build/ios/StyleDictionaryColor.h
✔︎  build/ios/StyleDictionaryColor.m
✔︎  build/ios/StyleDictionarySize.h
✔︎  build/ios/StyleDictionarySize.m

ios-swift
✔︎  build/ios-swift/StyleDictionary.swift

ios-swift-separate-enums
✔︎  build/ios-swift/StyleDictionaryColor.swift
✔︎  build/ios-swift/StyleDictionarySize.swift
```

Good for you! You have now built your first Style Dictionary!
Moving on, take a look at what we have built. This should have created a build directory and it should look like this:

<FileTree>

- config.json
- tokens.json
- script.js (empty)
- build/
  - android/
    - font_dimens.xml
    - colors.xml
  - compose/
    - StyleDictionaryColor.kt
    - StyleDictionarySize.kt
  - scss/
    - \_variables.scss
  - ios/
    - StyleDictionaryColor.h
    - StyleDictionaryColor.m
    - StyleDictionarySize.h
    - StyleDictionarySize.m
  - ios-swift/
    - StyleDictionary.swift
    - StyleDictionaryColor.swift
    - StyleDictionarySize.swift

</FileTree>

If you open `config.json` you will see there are 5 platforms defined:

- `scss`
- `android`
- `compose`
- `ios`
- `ios-swift`

Each platform has a `transformGroup`, `buildPath`, and `files`. The `buildPath` and `files` of the platform should match up to the files what were built.
These files can be viewed in the live demo above by clicking the output dropdown button.

Pretty nifty! This shows a few things happening:

1. The build system does a deep merge of all the token JSON files defined in the `source` attribute of `config.json`. This allows you to split up the token JSON files however you want. There are 2 JSON files with `color` as the top level key, but they get merged properly.
2. The build system resolves references to other design tokens. `{size.font.medium}` gets resolved properly.
3. The build system handles references to token values in other files as well as you can see in `tokens/color/font.json`.

Now let's make a change and see how that affects things. Open up `tokens/color/base.json` and change `"#111111"` to `"#000000"`. After you make that change, save the file and re-run the build command `style-dictionary build`. Open up the build files and take a look.

**Huzzah!**

Now go forth and create! Take a look at all the built-in [transforms](https://styledictionary.com/reference/hooks/transforms/predefined/) and [formats](https://styledictionary.com/reference/hooks/formats/predefined/).

:::tip
If you want to re-run Style Dictionary every time your tokens are changed, e.g. during local development, you can use a file-watcher like [Chokidar](https://github.com/open-cli-tools/chokidar-cli)
to watch file changes and re-run Style Dictionary when needed. In our playground this is done automatically but in order to replicate that behavior locally, implement the filewatcher in your NPM build script:

```sh
chokidar \"tokens.json\" -c \"node build-tokens.mjs\"
```

Or if you don't really need a wrapper build-tokens script and can use the Style Dictionary CLI directly:

```sh
chokidar \"tokens.json\" -c \"style-dictionary build\"
```

:::
